<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tk_Name manual page - Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tk C API</a> <small>&gt;</small> Name</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="Name.htm#M2" NAME="L474">NAME</A>
<DL><DD>Tk_Name, Tk_PathName, Tk_NameToWindow &mdash; convert between names and window tokens</DD></DL>
<DD><A HREF="Name.htm#M3" NAME="L475">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tk.h&gt;</B>
<DD>Tk_Uid
<DD><B>Tk_Name</B>(<I>tkwin</I>)
<DD>char *
<DD><B>Tk_PathName</B>(<I>tkwin</I>)
<DD>Tk_Window
<DD><B>Tk_NameToWindow</B>(<I>interp, pathName, tkwin</I>)
</DL>
<DD><A HREF="Name.htm#M4" NAME="L476">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DD><A HREF="Name.htm#M5" NAME="L477">DESCRIPTION</A>
<DD><A HREF="Name.htm#M6" NAME="L478">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tk_Name, Tk_PathName, Tk_NameToWindow &mdash; convert between names and window tokens
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tk.h&gt;</B><BR>
<A HREF="../TkLib/GetUid.htm">Tk_Uid</A><BR>
<B>Tk_Name</B>(<I>tkwin</I>)<BR>
char *<BR>
<B>Tk_PathName</B>(<I>tkwin</I>)<BR>
<A HREF="../TkLib/WindowId.htm">Tk_Window</A><BR>
<B>Tk_NameToWindow</B>(<I>interp, pathName, tkwin</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT><A HREF="../TkLib/WindowId.htm">Tk_Window</A> <B>tkwin</B> (in)<DD>
Token for window.
<P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (out)<DD>
Interpreter to use for error reporting.
<P><DT>const char <B>*pathName</B> (in)<DD>
Character string containing path name of window.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
Each window managed by Tk has two names, a short name that identifies
a window among children of the same parent, and a path name that
identifies the window uniquely among all the windows belonging to the
same main window.  The path name is used more often in Tk than the
short name;  many commands, like <B><A HREF="../TkCmd/bind.htm">bind</A></B>, expect path names as
arguments.
<P>
The <B>Tk_Name</B> macro returns a window's
short name, which is the same as the <I>name</I> argument
passed to <B><A HREF="../TkLib/CrtWindow.htm">Tk_CreateWindow</A></B> when
the window was created.  The value is returned
as a <A HREF="../TkLib/GetUid.htm">Tk_Uid</A>, which may be used just like a string pointer but also has
the properties of a unique identifier (see the manual entry for
<B><A HREF="../TkLib/GetUid.htm">Tk_GetUid</A></B> for details).
<P>
The <B>Tk_PathName</B> macro returns a hierarchical name for <I>tkwin</I>.
Path names have a structure similar to file names in Unix but with
dots between elements instead of slashes:  the main window for
an application has the path name
&ldquo;.&rdquo;;
its children have names like
&ldquo;.a&rdquo;
and
&ldquo;.b&rdquo;;
their children have names like
&ldquo;.a.aa&rdquo;
and
&ldquo;.b.bb&rdquo;;
and so on.  A window is considered to be a child of
another window for naming purposes if the second window was named
as the first window's <I>parent</I> when the first window was created.
This is not always the same as the X window hierarchy.  For
example, a pop-up
is created as a child of the root window, but its logical parent will
usually be a window within the application.
<P>
The procedure <B>Tk_NameToWindow</B> returns the token for a window
given its path name (the <I>pathName</I> argument) and another window
belonging to the same main window (<I>tkwin</I>).  It normally
returns a token for the named window, but if no such window exists
<B>Tk_NameToWindow</B> leaves an error message in interpreter
<I>interp</I>'s result
and returns NULL.  The <I>tkwin</I> argument to <B>Tk_NameToWindow</B>
is needed because path names are only unique within a single
application hierarchy.  If, for example, a single process has opened
two main windows, each will have a separate naming hierarchy and the
same path name might appear in each of the hierarchies.  Normally
<I>tkwin</I> is the main window of the desired hierarchy, but this
need not be the case:  any window in the desired hierarchy may be used.
<H3><A NAME="M6">KEYWORDS</A></H3>
<A href="../Keywords/N.htm#name">name</A>, <A href="../Keywords/P.htm#path name">path name</A>, <A href="../Keywords/T.htm#token">token</A>, <A href="../Keywords/W.htm#window">window</A>
<div class="copy">Copyright &copy; 1990 The Regents of the University of California.
<BR>Copyright &copy; 1994-1997 Sun Microsystems, Inc.
</div>
</BODY></HTML>
